\section{Foundation}
This chapter focuses on the foundation of \src{Common}: \src{CControl}, the \src{station}s and \src{dockable}s.

\subsection{Dockables}
A \src{CDockable}s is not much more than a set of properties like a ``title-icon'' and some \src{Component} which is to be shown to the user. A \src{CDockable} does not paint any decorations (like a title), handle any \src{MouseEvent}s or interacts with the user in any other way. Such jobs are handled by various manager-objects, factories and delegates. These objects need to know the \src{CDockable}s they work with and they need to be able to store information about them. To accomplish that each \src{CDockable} must be registered at a \src{CControl} and is associated with a unique identifier. Registering a \src{CDockable} is possible with one of the \src{addDockable}-methods \src{CControl} offers.

There are two types of \src{CDockable}s, \src{single-dockable}s and \linebreak \src{multi-dockable}s. The user usually won't notice any difference between these two types of dockables:
\begin{itemize}
 \item \src{Single-dockable}s are the ``tool windows''. There number is limited and the framework can assume that the client always knows all the possible ``tool windows''. When starting up, the client can either register all \src{SingleCDockable}s or the client can register some factories of type  \src{SingleCDockableFactory}. Also the client is responsible for storing the contents of \src{single-dockable}s.
 \item \src{Multi-dockable}s are the ``editor windows''. Their numbers are unlimited, and the framework assumes that the client does not know which editor windows exist. The client however knows what types of ``editor windows'' exist and has to provide factories of type \src{MultipleCDockableFactory}.
\end{itemize}

When a \src{CDockable} is created it is without location and it is invisible. Read chapter \ref{sec:location} to learn about locations and call \src{CDockable.setVisible} to show the \src{CDockable}.

\designbox{The interface \src{CDockable} has some awkward methods whose implementation is already described in the documentation. \src{CDockable} is not intended to be implemented by clients, but to be used by them. There is a subclass \src{AbstractCDockable} which provides the correct implementation for these awkward methods. Even in the framework itself no class (except \src{AbstractCDockable}) implements \src{CDockable} directly. The only reason for the existence of \src{CDockable} is to provide an abstraction from the implementation.}

\infobox{A \src{CDockable} is not a \src{Dockable}, but internally references a \src{Dockable}. This \src{Dockable} is always of type \src{CommonDockable}. It can be accessed through the method \src{intern} of \src{CDockable}. \src{DefaultCDockable} offers a method \src{createCommonDockable} which creates a new \src{DefaultCommonDockable}. Clients may override this method and provide their own implementation of \src{DefaultCommonDockable}. }

\subsubsection{SingleCDockable}
A \src{single-dockable} is created once, added to the controller and made visible. It remains in memory until explicitly removed from the \src{CControl} or the application terminates. Alternatively a \src{SingleCDockableFactory} can be used to lazily create a \src{dockable} once it is required.

The interface \src{SingleCDockable} represents a \src{single-dockable}, the class \src{DefaultSingleCDockable} is a convenient implementation of the interface. The class offers methods similar to those known from a \src{JFrame}, e.g. it has a content-pane where clients can add some \src{Component}s.

Examples for \src{single-dockable}s could be:
\begin{itemize}
  \item A browser has one panel ``history'', the panel is shown on a \linebreak \src{single-dockable}.
  \item A view that is most of the time invisible. A \src{single-dockable} is created lazily the first time when the view is shown.
\end{itemize}

\subsubsection{MultipleCDockable}
A set of \src{multi-dockable}s is used if the exact number of instances is not known prior to runtime. Before a \src{multi-dockable} can be used its factory (of type \src{MultipleCDockableFactory}) must be registered at a \src{CControl}. The factory offers methods to store and load the layout of a \src{dockable}. Of course there can be more than one \src{multi-dockable} per factory. Once the factory is registered, clients can add and remove \src{multi-dockable}s at any time.

The interface describing all \src{multi-dockable}s is \src{MultipleCDockable}, a convenient implementation is \src{DefaultMultipleCDockable}. This class offers most of the methods and properties a client should ever need.
Implementing a matching \src{MultipleCDockableFactory} is easy. There is a method to read and to write meta-information from or to a \src{MultipleCDockable}. Meta-information itself is a \src{MultipleCDockableLayout} which has methods to write or read its content to a stream (e.g. to file). There are no restrictions to what meta-information really is.

If a \src{multi-dockable} is made invisible, it should be removed from its \linebreak \src{CControl}. Otherwise old objects fill up memory until the application crashes with an \src{OutOfMemoryException}. Clients either need to remove the \src{dockable} by themselves or they can call \src{setRemoveOnClose(true)} to let the element be removed automatically once it becomes invisible

\warningbox{Any \src{multi-dockable} which is no longer required must be removed from the \src{CControl}, otherwise an \src{OutOfMemoryException} may happen.}

\infobox{Automatical removal is triggered when the \src{dockable} becomes invisible. This happens if the element does no longer have a root-parent. If a client makes the parent of a \src{multi-dockable} invisible, the \src{dockable} gets marked invisible as well. However, it does not get removed from its parent. Strange effect happen when the parent is made visible again: most of the decoration of the \src{dockable} is gone and some parts of the framework will ignore its existence.}

An example:
\begin{lstlisting}
CControl control = ...

MultipleCDockableFactory<MyDockable, MyLayoutInformation> = new ...
control.addMultipleDockableFactory( "unique id", factory );

MyDockable dockable = new ...
control.addDockable( dockable );
\end{lstlisting}
Notice that in line \src{4} a unique identifier needs to be assigned to the factory.

\codebox{A more sophisticated example can be found in the tutorial project. The name of the example is ``Guide/Common/Editors: MultipleCDockable''.}

Examples for \src{multiple-dockable}s are:
\begin{itemize}
 \item A text-editor can show many documents at the same time. Each document is shown in its own \src{dockable}.
 \item A 3D modeling software allows to see the modeled object from different angles. Each camera is a \src{dockable}.
\end{itemize}

\designbox{Why the distinction between \src{single-} and \src{multi-dockable}s? The algorithms to store and load the layout (place and size of \src{dockable}s) can either use existing objects or create new \src{dockable}s. Using existing objects is preferred because the overhead of creation can be - at least for complex views - high. \src{Single-} and \src{multi-dockable}s represent this gap.}

\subsubsection{Visibility}
Visibility has two meanings, ``logical visibility`` and ``true visibility``. If not stated otherwise, this document and all documentation always uses ``vsibility'' as an alias for ``logical visibility''.

\paragraph{Logical visibility}
A \src{dockable} is (logical) visible if it is either a child of a visible root-station or a registered root-station. With other words, logical visibility means that the \src{dockable} is somehow accessible to the user, it does not even imply that the user actually can see the \src{dockable} on the screen. Visibility can change through a set of events:
\begin{itemize}
 \item Obviously, calling \src{setVisible} of \src{CDockable} will change the visibility. If possible, the location of a \src{CDockable} will remembered and reused.
 \item Adding a \src{CDockable} to a station makes the \src{CDockable} visible. This may happen for example if using a \src{CGrid} (see chapter \ref{sec:location}).
 \item The user may close a dockable by clicking onto a special close-button. Clients may call \src{setCloseable} to allow or deny a user closing the dockable.
\end{itemize}

There are two listeners to monitor the visibility-state of dockables. Both can either be added to a \src{CDockable} or to a \src{CControl}. In the later case all known \src{dockable}s are monitored at the same time.

The first listener is the \src{CDockableStateListener}, it has a method \linebreak \src{visibilityChanged} which will be called whenever the visibility changes.

The second listener is the \src{CVetoClosingListener}. It receives a \linebreak \src{CVetoClosingEvent} before and after a set of \src{dockable}s gets closed. Clients can call the \src{cancel} method to prevent the closing-operation from finishing its work.

\warningbox{Using the close-button or changing the layout with \src{CControl.load} will always result in a cancelabe \src{CVetoClosingEvent}. However, some methods force the closing-operation to finish no matter what happens, the method \src{isCancelable} of \src{CVetoClosingEvent} will return \src{false} in such a case. Using the low-level methods of \src{Core}, one can even close a \src{dockable} without triggering a pre-close event. In such a case an unexpected \src{CVetoClosingEvent} is issued (see \src{isExpected()}). Naturally such an event cannot be canceled. }

\classbox{The close-action can be replaced by calling \src{putAction} with the key \src{ACTION\_KEY\_CLOSE} of \src{CDockable}. The action can be replaced at any time. Read more about actions in chapter \ref{sec:action}.}

\infobox{If the method \src{setLocation} of \src{AbstractCDockable} is called before the \src{dockable} is made visible, then the \src{dockable} is made visible at the supplied location. Read more about locations in chapter \ref{sec:location}.}

\paragraph{True visibility}
A \src{dockable} is truelly visible if the user can actually see the element on the screen. Clients can use the method \src{isShowing} of \src{CDockable} to find out whether a \src{dockable} is truelly visible. Also the \linebreak \src{CDockableLocationListener} can help clients to keep track of the true visibility.

It should be noted that logical visibility is required for the framework to acknowledge true visibility. Also the framework will not take things like ``is the main-frame minimized'' into account.

\warningbox{The \src{CDockableLocationListener} works asynchronously. Events not originating in the \src{EventDispatcherThread} may let the listener receive confusing if not plain wrong events.}

\subsubsection{Mode}
If a \src{CDockable} is visible then it always is in an extended-mode. The extended mode tells something about the behaviour of the \src{dockable} and where it is placed. The framework offers four default extended modes:
\begin{description}
 \item[normalized] The normal state of a \src{dockable}. It is placed on the main-frame of the application, but only covers a fraction of the main-frame.
 \item[maximized] A maximized \src{dockable} takes all the space it gets and often covers other \src{dockable}s.
 \item[minimized] A minimzed \src{dockable} is not directly visible. Only a button at one edge of the main-frame indicates the existance of the \src{dockable}. If the button is pressed then the \src{dockable} pops up. As soon as it loses focus it disapears again.
 \item[externalized] The \src{dockable} is on its own window. Per default the window is an undecorated \src{JDialog} and child of the main-frame.
\end{description}

Users can change the \src{extended-mode} either by dragging the \src{dockable} to a new place or by clicking some buttons that are visible in the title of each \src{dockable}. 

Clients can access and change the \src{extended-mode} by calling \linebreak \src{getExtendedMode} and \src{setExtendedMode} of \src{CDockable}. A \src{dockable} has no \src{extended-mode} if not visible. Furthermore clients can forbid a \src{dockable} to go into some \src{extended-mode}s, methods like \src{setMaximizable} of \src{DefaultCDockable} allow that. Finally clients can exchange the button that must be pressed by the user by calling \src{putAction} of \src{AbstractCDockable}. Keys for \src{putAction} are declared as \src{String} constants in \src{CDockable} with names like \src{ACTION\_KEY\_MINIMIZE}.

\src{Extended-mode}s are managed by the class \src{CLocationModeManager}. You can read more about that class in chapter \ref{sec:clocationmodemanager}.

\subsection{Stations}
Stations are needed to place and show \src{CDockable}s. A station provides the \src{Component}(s) (e.g. a \src{JPanel} or a dialog) that are the parents of the \src{dockables}. Stations are represented through the interface \src{CStation}.

\src{CStation}s delegate most of their work to some \src{DockStation} of \src{Core}. Like \src{dockables} a \src{CStation} requires a unique identifier. This identifier is used to persistently store and load layout information.

\infobox{
In general clients can introduce new stations, but a developer needs a lot of time to proberly implement a station:
\begin{enumerate}
 \item A working \src{DockStation} for the \src{Core} project must be written.
 \item For each extended-mode that matches the stations ability a \src{CModeArea} must be written. The \src{CModeArea} handles the locations (\src{CLocation}) of the \src{dockable}s on the station.
 \item It may even be necessary to write a new extended-mode altogether (which requires an implementation of \src{CLocationMode}).
 \item And then there are countless supportive classes that must be implemented: \src{CLocation}, \src{DockableProperty}, several factories, the list goes on...
\end{enumerate}
Conclusion: don't do this unless you have a lot of time to spare.
}

\classbox{The \src{DockStation} that is used by a \src{CStation} always implements the interface \src{CommonDockStation}.}

\subsubsection{All in one: CContentArea}
The preferred way to create stations is to use a \src{CContentArea}. A \src{CContentArea} is not a single \src{CStation} but a panel containing many stations. Each content-area has a center area where \src{dockable}s are layed out in a grid, and four small areas at the border where \src{dockable}s show up when they are minimized.

There is a default-\src{CContentArea} present and can be accessed through \linebreak \src{getContentArea} of \src{CControl}. A content-area can later be used like any other \src{Component}:
\begin{lstlisting}
JFrame frame = ...
CControl control = ...

CContentArea area = control.getContentArea();
frame.add( area );
\end{lstlisting}

If more than one content-area is needed then clients can use \linebreak \src{createContentArea} of \src{CControl} to create additional areas. These additional areas can later be removed through \src{removeStationContainer}. The default content-area cannot be removed.

\infobox{The default content-area is created lazily. There is no obligation to use or create it, clients can as well directly call \src{createContentArea} or not use them at all.}

\warningbox{While \src{CContentArea} has a public constructor clients should prefer to use the factory method \src{createContentArea}. In future releases the constructor might be changed.}

To place \src{dockables} onto a content-area a \src{CGrid} can be of help. With the method \src{deploy} the content of a whole \src{CGrid} can be put onto the center area. More about \src{CGrid} and other mechanisms to position elements are listed up in chapter \ref{sec:location}.

\subsubsection{Center area: CGridArea}
A \src{CGridArea} is kind of a lightweight version of \src{CContentArea}. A grid-area contains normalized and maximized \src{dockable}s. Other than a content-area it cannot show minimized \src{dockable}s.

\src{CGridArea}s should be created through the factory method \src{createGridArea} of \src{CControl}. If it is no longer required it can be removed through the method \src{removeStation}.

Like \src{CContentArea} \src{CGridArea} has a method \src{deploy} to add a whole set of \src{dockable}s quickly to the station.

Usage of a grid-area could look like this:

\begin{lstlisting}
JFrame frame = ...
CControl control = ...

CGridArea center = control.createGridArea( "center" );
frame.add( center.getComponent() );
\end{lstlisting}
Notice that in line \src{5} the method \src{getComponent} has to be called. This method returns the \src{Component} on which the station lies.

\classbox{Some more things that might be interesting:
\begin{itemize}
\item A grid-area implements \src{SingleCDockable}, hence it can be a child of another area. Remember that the area must be manually added to the \src{CControl} as \src{dockable}.
\item The method \src{setMaximizingArea} influences of what happens when a child of the area gets maximized. If \src{true} was given to the method then the child gets maximized within the boundaries of the grid-area. Otherwise the child might cover the area or even be transfered to another area.
\end{itemize}}

\subsubsection{Minimized: CMinimizeArea}
Most things that were said for \src{CGridArea} hold true for \src{CMinimizeArea} as well. A minimize-area should be created through \src{createMinimizeArea} of \src{CControl}.

\subsubsection{Grouping Dockables: CWorkingArea}
The \src{CWorkingArea} is a subclass of \src{CGridArea}. The difference between them is, that the property \src{working-area} is \src{false} for a grid-area, but \src{true} for a \src{CWorkingArea}. 

Having this property set to \src{true} places some constraints on the station:
\begin{itemize}
\item Children of this station cannot be moved to another station if that other station shows \src{dockable}s in normalized mode. For a user this means that children can only be minimized, maximized or externalized, but not dragged away.
\item The user cannot drop \src{dockable}s onto the station unless they are already children of the station.
\item If the station has no children then it appears as grey, empty space which does not go away.
\item Children of a working-area are not stored for temporary layout. For the user this means that applying a layout does neither affect the station, nor \src{dockable}s that can be put onto the station.
\end{itemize}

\src{CWorkingArea}s can be used to display a set documents. For example in an IDE (like \src{Eclipse} or \src{Netbeans}) each source file would get its own \src{CDockable} which then is put onto the working-area.

\infobox{The children of a \src{CWorkingArea} are often good candidates for being \src{MultipleCDockable}s.} 
